/**
 * 核心类型定义文件
 * 定义了系统中使用的主要数据类型和接口
 * 集中管理所有共享类型，确保类型一致性
 */

/**
 * 用户数据接口
 * 定义了系统中用户的核心数据结构，与MongoDB模型完全匹配
 */
export interface User {
  id: string | number;        // 用户ID，支持字符串(MongoDB)或数字(MySQL)格式
  _id?: string;               // MongoDB ID，兼容MongoDB存储系统
  username: string;           // 用户名，用于登录和显示，必填字段
  password?: string;          // 密码，通常API响应中不返回
  region: string;             // 所属区域，用于区域隔离（非超级管理员必填）
  roleId: string | number;    // 角色ID，关联到角色表(ObjectId)，必填字段
  roleState: boolean;         // 账号状态，true为启用，false为禁用
  default: boolean;           // 是否为默认用户，默认为false
  role?: Role;                // 关联的角色信息，包含权限数据（前端关联）
  avatar?: string;            // 用户头像URL
  introduction?: string;      // 用户自我介绍
  gender?: number;            // 性别：0-未知，1-男，2-女
  phone?: string;             // 联系电话
  email?: string;             // 电子邮箱
  location?: string;          // 所在地点
  permissionsVersion?: string; // 权限版本号，用于权限更新检测
  seqId?: number;             // 序列ID，用于业务逻辑中的唯一标识
  __v?: number;               // MongoDB版本号
}

/**
 * 角色数据接口
 * 定义了系统中角色的数据结构和权限关系，与MongoDB模型完全匹配
 */
export interface Role {
  id: string | number;       // 角色ID，支持字符串或数字
  _id?: string;              // MongoDB ID，兼容MongoDB存储
  roleName: string;          // 角色名称，如"超级管理员"、"管理员"、"编辑"等
  roleType: number;          // 角色类型：1-超级管理员, 2-管理员, 3-编辑
  rights: string[];          // 该角色拥有的权限路径列表
  seqId?: number;            // 序列ID，用于业务逻辑中的唯一标识
  __v?: number;              // MongoDB版本号
}

/**
 * 权限数据接口
 * 定义了系统权限项的数据结构，与MongoDB模型完全匹配
 */
export interface Right {
  id: string | number;        // 权限ID
  _id?: string;               // MongoDB ID
  title: string;              // 权限名称，如"用户管理"、"新闻管理"
  key: string;                // 权限键名，通常为URL路径，如"/user-manage"
  pagepermisson: number;      // 页面权限标识，1表示可见，0表示不可见
  grade: number;              // 权限等级：1-一级菜单，2-二级菜单
  children?: Right[];         // 子权限列表，用于构建层级权限树（前端扩展，非模型字段）
  seqId?: number;             // 序列ID，用于业务逻辑中的唯一标识
  __v?: number;               // MongoDB版本号
}

/**
 * 子权限数据接口
 * 定义了系统中子权限项(如按钮权限)的数据结构，与MongoDB模型完全匹配
 */
export interface Children {
  id?: string | number;        // 权限ID
  _id?: string;                // MongoDB ID
  title: string;               // 权限名称，如"创建用户"、"删除文章"
  key: string;                 // 权限键名，如"users:create"
  pagepermisson: number;       // 页面权限标识，0表示不可见，1表示可见
  grade: number;               // 权限等级
  rightId: string | number;    // 关联的父权限ID (ObjectId)
  seqId?: number;              // 序列ID，用于业务逻辑中的唯一标识
  __v?: number;                // MongoDB版本号
}

/**
 * 区域数据接口
 * 定义了系统中区域的数据结构，与MongoDB模型完全匹配
 */
export interface Region {
  id: string | number;        // 区域ID
  _id?: string;               // MongoDB ID
  title: string;              // 区域显示名称，如"北京"、"上海"（必填）
  value: string;              // 区域值，用于数据存储和匹配（必填，唯一）
  description: string;        // 区域描述，默认为空字符串
  departmentType: string;     // 部门类型：'news'|'sports'|'finance'|'politics'|'entertainment'|'tech'|'other'
  seqId?: number;             // 序列ID，用于业务逻辑中的唯一标识
  __v?: number;               // MongoDB版本号
}

/**
 * 分类数据接口
 * 定义了新闻分类的数据结构，与MongoDB模型完全匹配
 */
export interface Category {
  id: string | number;        // 分类ID
  _id?: string;               // MongoDB ID
  title: string;              // 分类名称，如"时政"、"体育"
  value: string;              // 分类值，用于数据存储和匹配
  seqId?: number;             // 序列ID，用于业务逻辑中的唯一标识
  __v?: number;               // MongoDB版本号
  
  // MongoDB文档对象，包含原始数据
  _doc?: {
    _id: string;
    title: string;
    value: string;
    __v: number;
    seqId: number;
    [key: string]: any;
  };
}

// 导出来自news.ts的类型定义，维护一处统一的类型
export type { News } from './news';
export { AuditState, PublishState } from './news';

/**
 * 通用API响应接口
 * 定义了系统所有API的统一响应格式
 */
export interface ApiResponse<T = unknown> {
  code: number;               // 状态码，200表示成功
  msg?: string;               // 响应消息
  data?: T;                   // 响应数据
  error?: string;             // 错误信息
}

/**
 * 通用分页请求参数接口
 * 定义了带分页功能的API请求参数格式
 */
export interface Pagination {
  page: number;               // 当前页码，从1开始
  limit: number;              // 每页条数，使用limit而非pageSize，与后端一致
  total: number;              // 总记录数
}

/**
 * 通用分页响应数据接口
 * 定义了带分页功能的API响应数据格式
 */
export interface PaginatedResponse<T = unknown> {
  items: T[];                 // 当前页的数据项数组
  page: number;               // 当前页码
  limit: number;              // 每页条数
  total: number;              // 总记录数
}

/**
 * 登录请求参数接口
 * 定义了登录API的请求参数格式
 */
export interface LoginParams {
  username: string;           // 用户名
  password: string;           // 密码
  captcha?: string;           // 验证码，部署环境可能需要
}

/**
 * Redux根状态接口
 * 定义了Redux存储的全局状态结构
 */
export interface RootState {
  collapsed: boolean;         // 侧边栏折叠状态
  loading: boolean;           // 全局加载状态
}

/**
 * 权限数据接口
 * 定义了细粒度权限控制的数据结构
 */
export interface Permission {
  id?: number;                // 权限ID
  _id?: string;               // MongoDB ID
  title: string;              // 权限名称
  code: string;               // 权限代码，用于权限检查
  description?: string;       // 权限描述
  status: boolean;            // 权限状态，true为启用，false为禁用
  createdAt?: string | number; // 创建时间
  updatedAt?: string | number; // 更新时间
}

/**
 * 权限组数据接口
 * 定义了权限组的数据结构，用于权限分组管理
 */
export interface PermissionGroup {
  id?: number;                // 权限组ID
  _id?: string;               // MongoDB ID
  title: string;              // 权限组名称
  permissions: string[] | Permission[]; // 包含的权限ID或权限对象
}

/**
 * 部门隔离错误类型枚举
 * 定义了部门隔离相关的错误类型
 */
export enum DepartmentIsolationErrorType {
  DEPARTMENT_ISOLATION = 'department_isolation', // 部门隔离错误，无权访问其他部门数据
  NO_PERMISSION = 'no_permission',               // 权限不足错误
  RESOURCE_NOT_FOUND = 'resource_not_found'      // 资源不存在错误
}

/**
 * 权限错误接口
 * 定义了权限相关错误的数据结构
 */
export interface PermissionError {
  type: string;               // 错误类型
  message: string;            // 错误消息
  code: string;               // 错误代码
  data?: unknown;             // 附加数据
}

/**
 * 部门操作结果接口
 * 定义了带部门隔离的操作结果格式
 */
export interface DepartmentOperationResult {
  success: boolean;           // 操作是否成功
  message?: string;           // 操作消息
  error?: PermissionError;    // 错误信息
  data?: unknown;             // 返回数据
}

/**
 * 统计数据接口
 * 定义了数据统计的通用格式
 */
export interface Statistics {
  [key: string]: number;      // 统计字段及其值
}

/**
 * 查询参数接口
 * 定义了API查询参数的通用格式
 */
export interface QueryParams {
  page?: number;              // 页码
  limit?: number;             // 每页条数，与后端一致
  [key: string]: unknown;     // 其他查询参数
} 